/**
 * 
 */
package jmine.tec.report.metadata;

import java.io.Serializable;
import java.util.Collection;
import java.util.EnumSet;
import java.util.Map;

import jmine.tec.report.cell.DataCell;
import jmine.tec.report.chart.ChartType;

/**
 * Representa a metadata da coluna, ou seja, os dados que a descrevem.
 * 
 * @author takeshi
 * @version 21/08/2007
 */
public interface ColumnMetaData extends Serializable {

    /**
     * Devolve a chave que representa esta coluna.
     * 
     * @return {@link String}
     */
    String getKey();

    /**
     * Devolve o 'label' desta coluna, a ser usado como chave de um arquivo de messages
     * 
     * @return {@link String}
     */
    String getLabel();

    /**
     * Recupera todos os parametros desta coluna, em uma {@link Map} de {@link String} para {@link ParameterDefinition}. Modificacoes no
     * {@link Map} nao devem refletir nesta {@link ColumnMetaData}.
     * 
     * @return {@link Map}
     */
    Map<String, ParameterDefinition> getAllParameterDefinitions();

    /**
     * Recupera um tipo de parametro para uma coluna ou <code>null</code> se o parametro nao esta disponivel.
     * 
     * @param key a chave do parametro
     * @return {@link ParameterType}
     */
    ParameterType getParameterType(String key);

    /**
     * Recupera um {@link ParameterDefinition} para a chave dada ou <code>null</code> se nenhum disponivel
     * 
     * @param key a chave do parametro
     * @return {@link ParameterDefinition}
     */
    ParameterDefinition getParameterDefinition(String key);

    /**
     * Devolv todos os {@link ParameterDefinition}. Modificacoes na colecao devolvida nao devem se refletir nesta instancia de
     * {@link ColumnMetaData}.
     * 
     * @return {@link Collection} de {@link ParameterDefinition}
     */
    Collection<ParameterDefinition> getParameters();

    /**
     * Devolve <code>true</code> se ha um parametro com essa chave definido para esta coluna
     * 
     * @param parameterKey the parameter key name
     * @return boolean
     */
    boolean hasParameter(String parameterKey);

    /**
     * Adds a parameter to this column, specifing the parameter name, the default value and the parameter type. The label used for the
     * parameter will be the name.
     * 
     * @param name {@link String} the parameter name
     * @param defaultValue {@link Object} the default value
     * @param type {@link ParameterType} the parameter type
     * @return {@link ColumnMetaData}
     * @see #addParameter(String, String, Object, ParameterType)
     */
    ColumnMetaData addParameter(String name, Object defaultValue, ParameterType type);

    /**
     * Adds a parameter to this column, specifing the parameter name, the default value and the parameter type. The label used for the
     * parameter will be the name.
     * 
     * @param name {@link String} the parameter name
     * @param label {@link String} the label to be used when rendering this parameter
     * @param referenceValue {@link Object} the default value
     * @param type {@link ParameterType} the parameter type
     * @return {@link ColumnMetaData}
     */
    ColumnMetaData addParameter(String name, String label, Object referenceValue, ParameterType type);

    /**
     * Adds an entity parameter to this parameter definition.
     * 
     * @param key {@link String}
     * @param entitiesMap {@link Map} of {@link String} to {@link String}
     * @return a {@link ColumnMetaData}
     */
    ColumnMetaData addEntityParameter(final String key, final Map<String, String> entitiesMap);

    /**
     * Returns all parameter definitions stored.
     * 
     * @return {@link Map} of {@link String} (the parameter name) -> {@link ParameterDefinition} the definition
     */
    Map<String, ParameterDefinition> getAllParameters();

    /**
     * Adds the given parameter definition
     * 
     * @param parameterDefinition {@link ParameterDefinition}
     * @return a {@link ColumnMetaData}
     */
    ColumnMetaData addParameter(final ParameterDefinition parameterDefinition);

    /**
     * Gets all the charts that this column can use.
     * 
     * @return the {@link EnumSet}
     */
    EnumSet<ChartType> getChartTypes();

    /**
     * An example {@link DataCell} to be used as a template for previewing pourposes.
     * 
     * @return {@link DataCell}
     */
    DataCell getExampleDataCell();

}
